#!/bin/bash

# 作用：删除 LANGUAGE 环境变量。
# 原因：LANGUAGE 变量通常用于指定程序的语言优先级（例如 LANGUAGE=en_US:zh_CN），可能会覆盖其他本地化设置。
# 取消该变量可避免其对后续命令的干扰。
unset LANGUAGE
# 作用：设置 LANG 和 LC_ALL 环境变量为 C 语言环境。
# 说明：C 是 Unix/Linux 系统中的标准默认 locale，它使用 ASCII 字符集，文本处理规则遵循 POSIX 标准（如英文消息、十进制小数点为 . 等）。
# 这确保脚本输出的文本（如错误信息、日志）格式统一，不受系统默认语言/地区影响。
export LANG=C
# 作用：设置 LC_ALL 环境变量为 C locale，强制覆盖所有其他本地化相关变量（如 LC_CTYPE、LC_TIME 等）。
# 说明：LC_ALL 是本地化设置的“最高优先级”变量，它会覆盖 LANG 和其他 LC_* 变量（如 LC_COLLATE 排序规则、LC_CTYPE 字符编码等）。
# 设置为 C 可确保所有文本处理（如字符串比较、字符分类、日期格式）严格遵循 POSIX 标准，避免因系统 locale 差异导致脚本逻辑错误（例如文件内容解析失败）。
export LC_ALL=C

#################################################

# exit on error
# 作用：当脚本中任何命令执行失败（返回非 0 状态码）时，立即终止脚本运行，
## 确保测试的严谨性和失败的及时捕获，保障了测试流程的可靠性和结果的准确性，避免错误状态的累积和传播
#set -e

#################################################

# $@ 表示所有位置参数的列表

# 获取当前脚本文件所在的目录路径，并将其存储在变量 BASEDIR 中
## 在 shell 脚本中，$0 表示当前脚本文件自身的路径（可能是相对路径或绝对路径，取决于执行脚本的方式）。
## dirname 是一个命令行工具，用于从文件路径中提取目录部分（即去除文件名，保留其所在的文件夹路径）。
#BASEDIR="$(dirname "$0")"

# 获取当前脚本文件的文件名（不包含路径），并将其存储在变量 BASENAME 中
#BASENAME="$(basename "$0")"

# 获取指定文件的文件名（不包含路径），并将其存储在变量 BASENAME 中
#BASENAME="$(basename /a/b/c.txt)"

#################################################

# 生成一个唯一的标识 [时间戳].[PID]，包含当前时间戳（格式：YYYYMMDDHHMMSS.ssssss）和当前进程 ID（$$）
## 作用：为生成的测试文件、目录或其他临时资源添加唯一标识，避免命名冲突和覆盖原有文件
## eg: 20250911201738.293033.1757
CUR_TIME_PID_SUFFIX="$(date "+%Y%m%d%H%M%S.%6N").$$"

#################################################

# 初始将所有颜色相关变量设为空字符串（默认不启用彩色输出）
# 仅在“未禁用彩色输出（NO_COLOR 未设置）”且“强制启用彩色（CLICOLOR_FORCE 设置）或输出到终端（stdout 是 tty）”时，才启用彩色文本输出
GREEN=""
YELLOW=""
RED=""
RESET=""
# 如果 NO_COLOR 未设置（默认情况），则进入内层条件判断是否启用彩色
if [ -z "$NO_COLOR" ] ; then
	# [ -n "$CLICOLOR_FORCE" ]：检查是否设置了 CLICOLOR_FORCE 环境变量（非空），
	## 若设置，则强制启用彩色输出，无论终端是否支持
	# [[ -t 1 ]]：检查标准输出（文件描述符 1，即 stdout）是否连接到终端（tty）
	if [ -n "$CLICOLOR_FORCE" ] || [[ -t 1 ]] ; then
		GREEN=$'\e[32m'   # 绿色文本的 ANSI 转义码
		YELLOW=$'\e[33m'  # 黄色文本的 ANSI 转义码
		RED=$'\e[31m'     # 红色文本的 ANSI 转义码
		RESET=$'\e[0m'    # 重置文本样式的 ANSI 转义码（恢复默认颜色/格式
	fi
fi

#################################################

# 作用：定义一个函数，用于输出错误信息并退出脚本。
# 参数：$* 表示任意数量的参数，将作为错误信息输出。
# 说明：该函数用于在脚本中报告错误情况，输出错误信息后退出脚本，返回非零退出码。
die() {
	printf '%s\n' "$*"
	exit 1
}

# 检查数组是否包含指定元素
# 用法：array_contains "element" "${array[@]}"
# 返回：0 包含，1 不包含
# 
# eg:
# FRUITS=("apple" "banana" "cherry")
# if array_contains "banana" "${FRUITS[@]}"; then
#    echo "找到了 banana"
# else
#    echo "未找到 banana"
# fi
array_contains() {
    local needle="$1"  # 将第一个参数保存为待查找的值（" needle"）
    local a            # 声明循环变量 `a`
    shift              # 移除第一个参数（needle），剩余参数作为数组元素
    for a; do          # 遍历剩余的所有参数（数组元素），等价于 `for a in "$@"; do`
        [ "$a" = "$needle" ] && return 0  # 若当前元素 `a` 等于 `needle`，返回 0（成功，表示找到）
    done
    return 1  # 循环结束未找到，返回 1（失败，表示未找到）
}

#################################################
